//
//  "$Id: Graphics.h 91860 2012-12-08 09:18:30Z li_weijun $"
//
//  Copyright(c)1992-2007, ZheJiang Dahua Technology Stock CO.LTD.
//  All Rights Reserved.
//
//	Description:	
//	Revisions:		Year-Month-Day  SVN-Author  Modification
//

#ifndef __GRAPHICS_API_H__
#define __GRAPHICS_API_H__

#include "Types.h"
#include "Defs.h"

#ifdef __cplusplus
extern "C" {
#endif

/// \defgroup GraphicsAPI API Graphics
/// 简单图形设备接口，获取FrameBuffer（帧缓冲）描述，设置Overlay（叠加）参数等等。
/// 渲染部分由上层实现，暂时不支持硬件加速。
/// \n 调用流程图:
/// \code
///    =========================================
///                   |                         
///           createGraphicsLayer 
///					  |
///         +---------|
///			|	updateSurface
///			|		  |
///         |     setAlpha
///         |         |
///         |    setKeyColor
///         |         |
///         +---------|
///                   |                         
///    =========================================
/// \endcode
/// @{

/// 图形颜色格式类型
typedef enum GraphicsColorFormat{  
	graphicsColorRGB555,	///< 16位表示一个象素。颜色分量位掩码为XRRRRRGG GGGBBBBB。
	graphicsColorRGB565,	///< 16位表示一个象素。颜色分量位掩码为RRRRRGGG GGGBBBBB。
	graphicsColorARGB888,	///< 32位表示一个像素。颜色分量位掩码为AAAAAAAARRRRRRRRGGGGGGGGBBBBBBBB
	graphicsColorBlackWhite,///< 1位表示一个像素
} GraphicsColorFormat;


/// 图形帧表面结构，128字节
typedef struct GraphicsSurface
{
	uchar *mem;			///< 显存块指针。
	uchar *mem0;		///< 保留。
	uchar *mem1;		///< 保留。
	int pitch;			///< 跨度，即显存一行扫描线的开始到下一行扫描线的开始存储空间的偏移，字节为单位。
	int width;			///< 面宽度，象素为单位。
	int height;			///< 面高度，象素为单位。
	int format;			///< 颜色格式，取GraphicsColorFormat类型值的值。
	int reserved[25];	///< 保留字节
} GraphicsSurface;


/// 图形层接口结构，512字节。
/// \detail 视频输出接口可能包含多个层，图形层是其中的一个，分辨率随视频输出分辨率变化。
typedef struct GraphicsLayer
{
	/// 底层私有数据
	void *priv;	


	/// 增加接口引用
	int (*addRef)(struct GraphicsLayer *thiz);


	/// 释放接口
	int (*release)(struct GraphicsLayer *thiz);


	/// 得到图形层全局表面。视频制式改变或者视频输出分辨率改变时可能会改变，GDI需要重新获取。
	/// 
	/// \param [in] thiz 图形层接口指针
	/// \param [out] surface 指向显示缓冲特征结构GraphicsSurface的指针。GDI直接通过
	///        显存块指针访问显存。图形设备只能选择GDI支持的颜色格式中的一种，如果GDI
	///        都不支持，就需要增加新的颜色格式，并扩充GDI功能。
	/// \retval 0  获取成功
	/// \retval <0  获取失败
	int (*getSurface)(struct GraphicsLayer *thiz, GraphicsSurface *surface);


	/// 设置图形的透明度。图形与图像在全屏范围内按此透明度叠加。
	/// 
	/// \param [in] thiz 图形层接口指针
	/// \param [in] alpha 要设置的当前透明度，值越低表示叠加时图像颜色的分量越低，也就
	///        越透明，取值0-255。
	/// \param [in] delta 透明度自动渐变值，每帧时间透明度加上此值，直到透明度变成最大
	///        或最小为止。值为0表示不渐变。
	/// \retval 0  设置成功
	/// \retval <0  设置失败
	int (*setAlpha)(struct GraphicsLayer *thiz, int alpha, int delta);


	/// 设置锁结颜色区域。图形与图像按锁结颜色叠加时，图像是源层，图形是目的层，图形的锁
	/// 结色区域将被视频替换。
	/// 
	/// \param [in] thiz 图形层接口指针
	/// \param [in] dwKeyLow 对应锁结色区域的颜色分量最小值，16进制表示为0x00BBGGRR，最高字节保留。
	/// \param [in] dwKeyHigh 对应锁结色区域的颜色分量最大值，16进制表示为0x00BBGGRR，最高字节保留。
	/// \retval 0  设置成功
	/// \retval <0  设置失败
	int (*setKeyColor)(struct GraphicsLayer *thiz, int keylow, int keyhigh);


	/// 设置硬件光标热点位置，但GDI一般使用软件光标，这个接口主要是供Windows模拟程序使用。
	///
	/// \param [in] thiz 图形层接口指针
	/// \param [in] x x坐标
	/// \param [in] y y坐标
	/// \retval 0  设置成功
	/// \retval <0  设置失败
	int (*setCursorPos)(struct GraphicsLayer *thiz, int x, int y);


	/// 刷新图形缓冲区域到显示设备。对于周期刷新的设备，此函数可以不实现。
	///
	/// \param [in] thiz 图形层接口指针
	/// \param [in] rects 矩形列表指针
	/// \param [in] num 矩形数目
	/// \retval 0  刷新成功
	/// \retval <0  刷新失败
	int (*updateRegion)(struct GraphicsLayer *thiz, Rect* rects, int num);


	/// 保留
	void *reserved[120];	
} GraphicsLayer;


/// 图形层接口描述，128字节
typedef struct GraphicsLayerDesc
{
	int channel;		///< 图像层通道号
	int card;			///< 子卡槽位号，0表示主板，>0表示子卡
	int reserved[30];	///< 保留
} GraphicsLayerDesc;


/// 创建图形层接口
///
/// \param [in] desc 图形层接口描述结构VideoInDesc指针
/// \param [out] layer 图形层接口指针的指针
/// \retval <0 创建失败
/// \retval 0 创建成功
int PAL_API createGraphicsLayer(GraphicsLayerDesc *desc, GraphicsLayer **layer);

/// @} end of group

#ifdef __cplusplus
}
#endif

#endif //__GRAPHICS_API_H__

